Documentation

Function that will be called when the transfer is accepted by a recipient (callback).

Parameters

[in]	transferId	transfer identifier
[in]	recipientAddr	IPv6 address of the recipient that accepted the transfer

Function that will be called when the transfer is finished (callback).

Parameters

[in]

transferId

transfer identifier

Type describing the state of the recipient.

Possible states of a single transfer.

Initializes the Bulk-Over-The-Air (BOTA) protocol Sender instance.

Parameters

[in]	botaSender	BOTA Sender instance
[in]	port	UDP port number used for BOTA transfers. This number should be the same in all BOTA-enabled devices. Consider using BOTA_DEFAULT_PORT value.
[in]	timeFunc	mandatory callback function that will provide time for the BOTA protocol instance

Return values

BOTA_RESULT_OK	if Bota was initialized successfully
BOTA_RESULT_FAILED_TO_REGISTER_UDP_SOCKET	if Bota was not initialized due to problem with UDP socket registration

Deinitializes the Bulk-Over-The-Air (BOTA) protocol Sender instance.

Runs the Bulk-Over-The-Air (BOTA) protocol instance for the sender.

Parameters

[in]

botaSender

BOTA Sender instance

Determines how much user memory is needed to handle the transfer to the given recipient/recipients.

In order to handle parallel transmissions to multiple recipients the BOTA protocol needs some temporary memory storage. This memory is called 'transfer space' and it is required for the user to provide such memory in order to run the BOTA transfer. This function returns the size of the transfer space that the user must provide in order to handle transfer to a given maximum number of recipients.

Parameters

[in]

maxNumberOfRecipients

maximum number of expected recipients

Returns

size (in number of bytes) of the required transfer space

Starts a new BOTA transfer.

This function starts a new Bulk-Over-The-Air (BOTA) transfer.

Parameters

[in]	botaSender	BOTA Sender instance
[in]	readFunc	function to read the source bulk memory
[in]	readAddr	address in the bulk memory where the source data starts
[in]	size	size of the bulk data to send (number of bytes)
[in]	recipientAddr	recipient address - group addressing is allowed
[in]	recipientPort	recipient port number
[in]	transferInfo	user-defined data that should describe the transfer contents to the recipient
[in]	transferInfoSize	size of the transfer information (number of bytes)
[in]	transferSpace	pointer to a operational memory space required to handle the transfer
[in]	transferSpaceSize	size of the provided transfer memory (number of bytes)
[in]	transferPolicy	optional structure defining policies for the transfer (see BotaSenderTransferPolicy)
[in]	onTransferAccepted	optional callback function that will be called when the transfer is accepted by a node
[in]	onTransferFinished	optional callback function that will be called when the transfer is finished
[out]	transferId	optional place to store transfer identifier

Return values

BOTA_RESULT_OK	- if the transfer was started successfully
BOTA_RESULT_INVALID_INPUT_ARGUMENT	- if at least one of the input arguments was invalid
BOTA_RESULT_FAILED_TO_REGISTER_NEW_TRANSFER	- if the transfer was not started because new transfer could not be registered (possibly too many transfers are ongoing)

Gets BOTA transfer status.

This function retrieves the status of an ongoing BOTA transfer. The returned structure describes the current status of the transfer.

Note, that if the BotaSenderTransferStatus::transferState field is set to BOTA_SENDER_TRANSFER_STATE_UNKNOWN then the transfer was not found in the senders transfer list. Perhaps it was ended or the provided transferId was invalid. In such case BotaSenderTransferStatus::totalBytes and BotaSenderTransferStatus::transferredBytes are set to 0.

Parameters

[in]	botaSender	BOTA Sender instance
[in]	transferId	transfer identifier, as returned by BOTA_SENDER_StartTransfer

Returns

structure describing the transfer status at the sender

Gets the number of recipients for an ongoing BOTA transfer.

This function gets the number of nodes that participate as recipients in the ongoing BOTA transfer.

Parameters

[in]	botaSender	BOTA Sender instance
[in]	transferId	transfer identifier, as returned by BOTA_SENDER_StartTransfer

Returns

number of recipients

Gets the status of a single BOTA transfer recipient.

Parameters

[in]	botaSender	BOTA Sender instance
[in]	transferId	transfer identifier, as returned by BOTA_SENDER_StartTransfer
[in]	index	recipient index (must be less than the value returned by BOTA_SENDER_GetRecipientCount)

Returns

pointer to a structure describing the status of the transfer recipient or NULL if there was no such recipient

Ends a BOTA transfer.

This function causes the given BOTA transfer to end.

If the transfer is finished (BOTA_SENDER_TRANSFER_STATE_FINISHED) or an error occurred (BOTA_SENDER_TRANSFER_STATE_ERROR) then this call removes the transfer from the BOTA transfer list, making space for other transfers.

If the transfer is ongoing then it is canceled.

Parameters

[in]	botaSender	BOTA Sender instance
[in]	transferId	transfer identifier, as returned by BOTA_SENDER_StartTransfer

Return values

BOTA_RESULT_OK	- if the transfer was ended successfully
BOTA_RESULT_INVALID_INPUT_ARGUMENT	- if at least one of the input arguments was invalid

Restarts a BOTA transfer.

This function causes the given BOTA transfer to be restarted.

When the transfer is finished (BOTA_SENDER_TRANSFER_STATE_FINISHED) but (for example) not all recipients received the data, then the transfer can be retried.

Parameters

[in]	botaSender	BOTA Sender instance
[in]	transferId	transfer identifier, as returned by BOTA_SENDER_StartTransfer

Return values

BOTA_RESULT_OK	- if the transfer was retried successfully
BOTA_RESULT_INVALID_INPUT_ARGUMENT	- if at least one of the input arguments was invalid